// File: jmcomic-core/src/main/java/dev/jukomu/jmcomic/client/JmcomicClient.java
package dev.jukomu.jmcomic.client;

import dev.jukomu.common.postman.Postman;
import dev.jukomu.jmcomic.entity.JmFavoritePage;
import dev.jukomu.jmcomic.entity.JmSearchPage;

import java.util.Iterator;
import java.util.List;
import java.util.Map;

/**
 * 对应Python的JmcomicClient，聚合所有禁漫客户端接口。
 */
public interface JmcomicClient extends
        JmImageClient,
        JmDetailClient,
        JmUserClient,
        JmSearchAlbumClient,
        JmCategoryClient,
        Postman { // 也继承Postman接口，允许直接进行HTTP请求

    /**
     * 获取客户端键名。
     *
     * @return 键名字符串。
     */
    String getClientKey();

    /**
     * 获取当前客户端的域名配置。
     *
     * @return 域名列表。
     */
    List<String> getDomainList();

    /**
     * 设置当前客户端的域名配置。
     *
     * @param domainList 域名列表。
     */
    void setDomainList(List<String> domainList);

    /**
     * 设置客户端级别的缓存Map。
     *
     * @param cacheMap 缓存Map。
     */
    void setCacheMap(Map<Object, Object> cacheMap);

    /**
     * 获取客户端级别的缓存Map。
     *
     * @return 缓存Map。
     */
    Map<Object, Object> getCacheMap();

    /**
     * 根据API路径和域名生成完整的API URL。
     *
     * @param apiPath API路径。
     * @param domain  域名。
     * @return 完整的API URL。
     */
    String ofApiUrl(String apiPath, String domain);

    /**
     * 获取可用的禁漫网页域名。
     *
     * @return 域名字符串。
     */
    String getHtmlDomain() throws Exception;

    /**
     * 获取所有可用的禁漫网页域名。
     *
     * @return 域名列表。
     */
    List<String> getHtmlDomainAll() throws Exception;

    /**
     * 通过GitHub页面获取所有可用的禁漫网页域名。
     *
     * @return 域名Set。
     */
    java.util.Set<String> getHtmlDomainAllViaGithub() throws Exception;

    /**
     * 收藏夹内容的生成器。
     *
     * @param page     起始页码。
     * @param orderBy  排序方式。
     * @param folderId 收藏夹ID。
     * @param username 用户名。
     * @return JmFavoritePage的迭代器。
     */
    Iterator<JmFavoritePage> favoriteFolderGen(int page, String orderBy, String folderId, String username);

    /**
     * 搜索结果的生成器。
     *
     * @param searchQuery 搜索查询词。
     * @param mainTag     主标签。
     * @param page        起始页码。
     * @param orderBy     排序方式。
     * @param time        时间范围。
     * @param category    类别。
     * @param subCategory 副类别。
     * @return JmSearchPage的迭代器。
     */
    Iterator<JmSearchPage> searchGen(String searchQuery, int mainTag, int page, String orderBy, String time, String category, String subCategory);

    /**
     * 分类过滤结果的生成器。
     *
     * @param page        起始页码。
     * @param time        时间范围。
     * @param category    类别。
     * @param orderBy     排序方式。
     * @param subCategory 副类别。
     * @return JmSearchPage的迭代器。
     */
    Iterator<JmSearchPage> categoriesFilterGen(int page, String time, String category, String orderBy, String subCategory);

    /**
     * 判断当前客户端实例是否为指定类型。
     *
     * @param clientType 客户端Class对象。
     * @return 如果是指定类型返回 true。
     */
    boolean isGivenType(Class<? extends JmcomicClient> clientType);
}